1. Rozszerzanie Pythona za pomocą C lub C++

Jest całkiem łatwo dodać nowe wbudowane moduły do Pythona, jeśli znasz się na programowaniu w C. Takie moduły rozszerzające mogą zrobić dwie rzeczy których nie da się zrobić bezpośrednio w Pythonie: mogą wypełnić nowe wbudowane typy przedmiotów i mogą odwołać się do zadań bibliotecznych C i odwołań systemowych.

Aby wspierać rozszerzenia, API Pythona (Application Programmers Interface) określa zbiór funkcji, makropoleceń i zmiennych, które dostarczają dostęp do większości aspektów systemu czasu-wykonania Pythona. API Pythona jest załączane w źródłowym pliku C przez załączenie pliku nagłówkowego "Python.h".

Kompilacja rozszerzających modułów zależy od jego zamierzonego użycia zarówno jak też od ustawień twojego systemu; szczegóły są dane w późniejszych rozdziałach.

Informacja

The C extension interface is specific to CPython, and extension modules do not work on other Python implementations. In many cases, it is possible to avoid writing C extensions and preserve portability to other implementations. For example, if your use case is calling C library functions or system calls, you should consider using the ctypes module or the cffi library rather than writing custom C code. These modules let you write Python code to interface with C code and are more portable between implementations of Python than writing and compiling a C extension module.

Let’s create an extension module called spam (the favorite food of Monty Python fans…) and let’s say we want to create a Python interface to the C library function system() 1. This function takes a null-terminated character string as argument and returns an integer. We want this function to be callable from Python as follows:

Zaczynając od stworzenia pliku spammodule.c (Historycznie, jeśli moduł był nazwany spam, plik C zawierający jego wypełnienie jest nazywany spammodule.c; jeśli nazwa modułu jest bardzo długa, jak np spammify, nazwa modułu może być po prostu spammify.c.)

The first two lines of our file can be:

które dociągają API Pythona (możesz dodać komentarz opisujący przeznaczenie modułu i uwagi na temat praw autorskich jeśli masz ochotę).

Informacja

Jako że Python może definiować pewne definicje preprocesora, które wpływają na pliki nagłówkowe na niektórych systemach, musisz załączyć plik Python.h przed jakimikolwiek standardowymi nagłówkami.

It is recommended to always define PY_SSIZE_T_CLEAN before including Python.h. See Wydobywanie parametrów w zadaniach rozszerzających for a description of this macro.

All user-visible symbols defined by Python.h have a prefix of Py or PY, except those defined in standard header files. For convenience, and since they are used extensively by the Python interpreter, "Python.h" includes a few standard header files: , , , and . If the latter header file does not exist on your system, it declares the functions malloc(), free() and realloc() directly.

Następną rzeczą którą dodajemy do naszego pliku modułu jest zadanie C które będzie wzywane gdy wyrażenie języka pytonowskiego spam.system(string) zostanie obliczone (zobaczymy niedługo, jak to się kończy wywołaniem):

Istnieje prosta zamiana nazw z listy parametrów w języku pytonowskim (dla przykładu, pojedyncze wyrażenie "ls -l") do parametrów przekazanych do zadania C. Zadanie C zawsze ma dwa parametry, dla wygody nazywane sam - z ang. - self i args.

Parametr sam - z ang. - self - wskazuje na przedmiot modułu dla zadań na poziomie-modułu; dla sposobu postępowania wskazywałby na przykład przedmiotu.

The args argument will be a pointer to a Python tuple object containing the arguments. Each item of the tuple corresponds to an argument in the call’s argument list. The arguments are Python objects — in order to do anything with them in our C function we have to convert them to C values. The function PyArg_ParseTuple() in the Python API checks the argument types and converts them to C values. It uses a template string to determine the required types of the arguments as well as the types of the C variables into which to store the converted values. More about this later.

PyArg_ParseTuple() returns true (nonzero) if all arguments have the right type and its components have been stored in the variables whose addresses are passed. It returns false (zero) if an invalid argument list was passed. In the latter case it also raises an appropriate exception so the calling function can return NULL immediately (as we saw in the example).

An important convention throughout the Python interpreter is the following: when a function fails, it should set an exception condition and return an error value (usually -1 or a NULL pointer). Exception information is stored in three members of the interpreter’s thread state. These are NULL if there is no exception. Otherwise they are the C equivalents of the members of the Python tuple returned by sys.exc_info(). These are the exception type, exception instance, and a traceback object. It is important to know about them to understand how errors are passed around.

Sprzęg języka pytonowskiego określa pewien zestaw zadań do ustawiania różnych rodzajów wyjątków.

The most common one is PyErr_SetString(). Its arguments are an exception object and a C string. The exception object is usually a predefined object like PyExc_ZeroDivisionError. The C string indicates the cause of the error and is converted to a Python string object and stored as the „associated value” of the exception.

Another useful function is PyErr_SetFromErrno(), which only takes an exception argument and constructs the associated value by inspection of the global variable errno. The most general function is PyErr_SetObject(), which takes two object arguments, the exception and its associated value. You don’t need to Py_INCREF() the objects passed to any of these functions.

You can test non-destructively whether an exception has been set with PyErr_Occurred(). This returns the current exception object, or NULL if no exception has occurred. You normally don’t need to call PyErr_Occurred() to see whether an error occurred in a function call, since you should be able to tell from the return value.

When a function f that calls another function g detects that the latter fails, f should itself return an error value (usually NULL or -1). It should not call one of the PyErr_* functions — one has already been called by g. f’s caller is then supposed to also return an error indication to its caller, again without calling PyErr_*, and so on — the most detailed cause of the error was already reported by the function that first detected it. Once the error reaches the Python interpreter’s main loop, this aborts the currently executing Python code and tries to find an exception handler specified by the Python programmer.

(There are situations where a module can actually give a more detailed error message by calling another PyErr_* function, and in such cases it is fine to do so. As a general rule, however, this is not necessary, and can cause information about the cause of the error to be lost: most operations can fail for a variety of reasons.)

To ignore an exception set by a function call that failed, the exception condition must be cleared explicitly by calling PyErr_Clear(). The only time C code should call PyErr_Clear() is if it doesn’t want to pass the error on to the interpreter but wants to handle it completely by itself (possibly by trying something else, or pretending nothing went wrong).

Every failing malloc() call must be turned into an exception — the direct caller of malloc() (or realloc()) must call PyErr_NoMemory() and return a failure indicator itself. All the object-creating functions (for example, PyLong_FromLong()) already do this, so this note is only relevant to those who call malloc() directly.

Also note that, with the important exception of PyArg_ParseTuple() and friends, functions that return an integer status usually return a positive value or zero for success and -1 for failure, like Unix system calls.

Finally, be careful to clean up garbage (by making Py_XDECREF() or Py_DECREF() calls for objects you have already created) when you return an error indicator!

The choice of which exception to raise is entirely yours. There are predeclared C objects corresponding to all built-in Python exceptions, such as PyExc_ZeroDivisionError, which you can use directly. Of course, you should choose exceptions wisely — don’t use PyExc_TypeError to mean that a file couldn’t be opened (that should probably be PyExc_IOError). If something’s wrong with the argument list, the PyArg_ParseTuple() function usually raises PyExc_TypeError. If you have an argument whose value must be in a particular range or must satisfy other conditions, PyExc_ValueError is appropriate.

Możesz też określić nowy wyjątek który jest niepowtarzalny dla twojego modułu. Dla tego, zwykle deklarujesz przedmiot statycznej zmiennej na początku pliku:

and initialize it in your module’s initialization function (PyInit_spam()) with an exception object: